#import <Foundation/Foundation.h>
#import <MapKit/MapKit.h>
#import "FoursquareVenue.h"
#import "FoursquareVenueCollectionDelegate.h"

//  This Foursquare integration is possible thanks to the Foursquare API by
//  Eric Butler and associates.
//
//  Copyright (C) 2010 Eric Butler <eric@codebutler.com>

/**
 * A FoursquareVenueCollection is an object representing a collection
 * of venues in the Foursquare system.
 *
 * Provides the functionality to perform necessary queries on the set of 
 * venues.
 *
 * Code used within this class and the supporting API was written by 
 * Eric Butler and other associates.
 *
 * The supporting API can be found in ./FourSquareAPI folder.
 *
 * @author      Eric Butler
 * @author      James Lin
 * @version     2.3.3 
 * @since       2.1.3
 */
@interface FoursquareVenueCollection : NSObject {
	id<FoursquareVenueCollectionDelegate> delegate;        // Delegate handling response
	NSMutableArray*                       venueCollection; // Collection of venues
}

/**
 * Retrieve the shared instance of the Foursquare venue collection.
 *
 * @return  the shared instance of FoursquareVenueCollection
 */
+ (FoursquareVenueCollection*)sharedVenueCollection;

/**
 * Get the number of venues in the collection.
 *
 * @return  the number of venues in the collection
 */
- (NSInteger)size;

/**
 * Get the list of venues.
 *
 * @return  the list of venues
 */
- (NSArray*)allVenues;

/**
 * Retrieve a fresh set of nearby venue data.
 *
 * Currently only supports a maximum of 50 venues as stated by the API.
 *
 * @param location     the user location
 * @param theDelegate  the delegate handling update notification
 * @param venueLimit   the maximum number of venues to find
 * @param identifier   the unique identifier for this update request
 */
- (void)updateWithUserLocation:(CLLocation*)location 
				   andDelegate:(id<FoursquareVenueCollectionDelegate>)theDelegate 
					venueLimit:(NSUInteger)venueLimit 
					identifier:(NSUInteger)identifier;

/**
 * Find a fresh set of nearby venue specials.
 *
 * @param location       the user location
 * @param theDelegate    the delegate handling search notification
 * @param specialsLimit  the maximum number of specials to find
 */
- (void)findSpecialsWithUserLocation:(CLLocation*)location 
						 andDelegate:(id<FoursquareVenueCollectionDelegate>)theDelegate 
					   specialsLimit:(NSUInteger)specialsLimit;

/**
 * Find the venue given a list of possible venue names.
 *
 * @param name  possible names of venue to find
 * @param       the Foursquare if found;
 *              nil otherwise
 */
- (FoursquareVenue*)findVenueWithNames:(NSArray*)names;

@end
